Skip to content

docs: bump all documentation dependencies #1325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

docs: bump all documentation dependencies #1325

wants to merge 16 commits into from
+103 −61

Conversation

onerandomusername
Copy link
Member

@onerandomusername onerandomusername commented Aug 28, 2025 •
edited by shiftinv
Loading

What Changed

Bump all documentation dependencies, restrict them to python 3.11, bump the entire documentation to 3.11 too.

Changelogs

Deprecations

sphinx-hoverxref uses some interfaces removed in sphinx 9.0. However, sphinx-hoverxref is it itself deprecated, so we should drop it anyhow.

Depends on

#1341, which limits docs to only being typechecked on the version it runs on.

@shiftinv shiftinv added t: dependencies Addition/update/removal of dependencies t: documentation Improvements or additions to documentation/examples labels Aug 29, 2025
@shiftinv
Copy link
Member

Are you planning on dropping hoverxref in this or in a separate PR?

@onerandomusername
Copy link
Member Author

Are you planning on dropping hoverxref in this or in a separate PR?

Planning to drop hoverxref on another PR.

This one is also blocked by needing to figure out pyright 3.8-3.10 overrides

onerandomusername
onerandomusername commented Sep 2, 2025
View reviewed changes
@onerandomusername onerandomusername force-pushed the docs/bump-sphinx-8 branch 3 times, most recently from 4857b3b to ae1143c Compare September 5, 2025 02:31
@onerandomusername onerandomusername force-pushed the docs/bump-sphinx-8 branch 2 times, most recently from ea89f22 to 47f9903 Compare September 17, 2025 21:56
@read-the-docs-community Read the Docs Community
Copy link

read-the-docs-community bot commented Sep 17, 2025 •
edited
Loading

Documentation build overview

📚 disnake | 🛠️ Build #29781613 | 📁 Comparing 8913dc1 against latest (613e01d)


🔍 Preview build

Show files changed (71 files in total): 📝 71 modified | ➕ 0 added | ➖ 0 deleted
File Status
404.html 📝 modified
api.html 📝 modified
discord.html 📝 modified
faq.html 📝 modified
index.html 📝 modified
intents.html 📝 modified
intro.html 📝 modified
logging.html 📝 modified
migrating.html 📝 modified
migrating_to_async.html 📝 modified
quickstart.html 📝 modified
search.html 📝 modified
version_guarantees.html 📝 modified
whats_new.html 📝 modified
whats_new_legacy.html 📝 modified
api/abc.html 📝 modified
api/activities.html 📝 modified
api/app_commands.html 📝 modified
api/app_info.html 📝 modified
api/audit_logs.html 📝 modified
api/automod.html 📝 modified
api/channels.html 📝 modified
api/clients.html 📝 modified
api/components.html 📝 modified
api/emoji.html 📝 modified
api/entitlements.html 📝 modified
api/events.html 📝 modified
api/exceptions.html 📝 modified
api/guild_scheduled_events.html 📝 modified
api/guilds.html 📝 modified
api/index.html 📝 modified
api/integrations.html 📝 modified
api/interactions.html 📝 modified
api/invites.html 📝 modified
api/localization.html 📝 modified
api/members.html 📝 modified
api/messages.html 📝 modified
api/misc.html 📝 modified
api/permissions.html 📝 modified
api/roles.html 📝 modified
api/skus.html 📝 modified
api/soundboard.html 📝 modified
api/stage_instances.html 📝 modified
api/stickers.html 📝 modified
api/subscriptions.html 📝 modified
api/ui.html 📝 modified
api/users.html 📝 modified
api/utilities.html 📝 modified
api/voice.html 📝 modified
api/webhooks.html 📝 modified
api/widgets.html 📝 modified
ext/commands/additional_info.html 📝 modified
ext/commands/api.html 📝 modified
ext/commands/cogs.html 📝 modified
ext/commands/commands.html 📝 modified
ext/commands/extensions.html 📝 modified
ext/commands/index.html 📝 modified
ext/commands/slash_commands.html 📝 modified
ext/tasks/index.html 📝 modified
ext/commands/api/app_commands.html 📝 modified
ext/commands/api/bots.html 📝 modified
ext/commands/api/checks.html 📝 modified
ext/commands/api/cogs.html 📝 modified
ext/commands/api/context.html 📝 modified
ext/commands/api/converters.html 📝 modified
ext/commands/api/events.html 📝 modified
ext/commands/api/exceptions.html 📝 modified
ext/commands/api/help_commands.html 📝 modified
ext/commands/api/index.html 📝 modified
ext/commands/api/misc.html 📝 modified
ext/commands/api/prefix_commands.html 📝 modified

@onerandomusername onerandomusername marked this pull request as ready for review September 20, 2025 20:33
@onerandomusername onerandomusername added the s: needs review Issue/PR is awaiting reviews label Sep 23, 2025
@github-project-automation github-project-automation bot moved this to Todo in disnake Sep 23, 2025
@shiftinv
Copy link
Member

shiftinv commented Sep 28, 2025 •
edited
Loading

Looks good overall! A couple things:

  • Could we just filter the sphinx 9.0 deprecation warning for the time being, until we replace hoverxref properly?
  • Low priority, but this info log is pretty noisy, could potentially filter it
  • Similarly, Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`. - we could update this in conf.py as well. It's always been doing this conversion, but the log was only added recently
  • On subsequent autobuild runs, I'm getting Aborted attempted copy from rendered template _templates/api_redirect.js_t [...]. As far as I can tell, we now need a force=True here:

    disnake/docs/extensions/redirects.py

    Lines 40 to 44 in e93670d

    copy_asset_file(
    SCRIPT_PATH,
    str(Path(app.outdir, "_static", "api_redirect.js")),
    context=context,
    )
    • Somewhat related, since the copy_redirect_script hook here takes Exception instead of Exception | None, type checkers consider most of that function dead code

@shiftinv
Copy link
Member

shiftinv commented Sep 28, 2025 •
edited
Loading

A couple more things I noticed:

  • Sphinx added the classic purple coloring to visited links, the contrast with the documentation's background color is awful (contrast ratio of 1.05):
    image
    I think the best solution would be to override that selector and remove the highlight, visited link tracking for a documentation website seems fairly pointless to me anyway.
  • Maybe it's just the PR preview build, but search is pretty broken outside of the indexed results; it requests pages like https://disnake--1325.org.readthedocs.build/en/1325/undefinedext/tasks/index.html, which obviously don't resolve. Haven't really investigated why, yet.
  • Redirects from the old api.html#ref to api/page.html#ref are broken, since URL_ROOT no longer exists (see previous point). We should use document.documentElement.dataset.content_root instead.

(also, thanks for including links to all the changelogs <3)

@shiftinv
fix: replace obsolete URL_ROOT with html data field for search
0b74527
@shiftinv
fix: override/reset :visited highlight
855988d
@shiftinv
fix: remove duplicate documentation_options.js script
07defce 
see sphinx-doc/sphinx@ee5560b
@shiftinv
chore: rename .js_t to .js.jinja
82f2d25 
https://www.sphinx-doc.org/en/master/development/html_themes/index.html#static-templates
@shiftinv
fix: suppress two verbose/unimportant sphinx logs
f568b9c
@shiftinv
fix: ignore __pycache__ when autobuilding, to avoid building twice
cc80518
@shiftinv
fix: base custom search scorer on base title score
b5e0496 
this is by no means perfect; long story short, sphinx changed
the search scorer algorithm to actually take the configured `title`
score (15) into account for matching titles, instead of a fixed 100.
This, in turn, meant that any and all page matches would now be ranked at the bottom,
since the custom search scorer inflates the score of all `disnake.*` objects to
a score right below 100.

To resolve this, the scorer now assigns these API results a score of
14-15, i.e. right below pages with matching titles again.
API results with a longer or later submatch continue to receive a higher score penalty,
and are therefore closer to 14 rather than 15.
@shiftinv
chore: comment debug console.log again
8913dc1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@shiftinv shiftinv Awaiting requested review from shiftinv

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

s: needs review Issue/PR is awaiting reviews skip news t: dependencies Addition/update/removal of dependencies t: documentation Improvements or additions to documentation/examples

Projects

disnake
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@onerandomusername @shiftinv